Refuse an amount decimal cannot hold instead of guessing at it - #151

… on it

Review findings.

ToString interpolates ValueAsNumber, so making the getter throw made ToString
throw with it - for positives, which used to print a clamped number, as well as
for negatives, which already threw. By convention ToString does not throw, and
the places it is reached from are logging, string interpolation and a debugger's
watch window: exactly where someone would be while working out why an amount is
unusual. Failing there hides the value at the moment it is most wanted. It now
falls back to the raw string, which is what the node sent.

Two tests were missing behind claims already made.

GetBalanceChanges documents that it throws on an out-of-range amount, and
nothing exercised that through GetBalanceChanges - only a hand-written
subtraction imitating what it does. Imitating the arithmetic proves the
arithmetic; it does not prove the method reaches it, which is what the
documentation promises. Now driven through the method, on a negative balance in
a RippleState node - the ordinary shape from the low account's side, and the
case that used to fail as FormatException.

And one edge is documented rather than fixed: writing decimal.MaxValue through
the setter formats with G16, which rounds the mantissa up past what decimal
holds, so the SDK can write a string the ledger would accept and then refuse to
read it. The window is the last ~7e12 below decimal.MaxValue, reachable only by
assigning a number no token amount would be, and changing how the setter rounds
would touch every round trip in the type to rescue a value nobody writes. The
test states the decision so the next person meets one rather than a surprise.

Restoring the clamp now fails seven tests.

Checked against rippled first, which changed what this should be.

I had proposed replacing G16 with truncation, on the belief that rippled
truncates a mantissa when normalising. It does not: Number.cpp sets
RoundingMode::ToNearest as the default, which is what G16 already does. Making
the SDK truncate would have moved it away from the protocol, not toward it. The
rounding stays.

What is left is narrow. At the top of decimal's own range, rounding to nearest
rounds up past what the type holds, so the setter wrote a string it then refused
to read - a valid ledger amount the SDK produced and could not consume. There,
and only there, the sixteenth digit is truncated instead; truncating cannot
overflow, because dropping digits only moves a number toward zero.

Dust is pinned by a test. Balances like 0.000000000000000001 arrive from the
network and must go back out, and they are safe because the ledger's limit is
sixteen significant digits while dust carries one. The test exists because the
obvious way to bound precision - truncating to sixteen decimal places rather
than significant digits - turns 1e-18 into zero, and a remainder would vanish in
silence. That mutation fails it.

ValueAsNumber_16Digits_NeverRoundsUp asserted that a round trip must not
increase a value. The protocol makes no such promise, and the test could not
have caught a violation anyway: its input has exactly sixteen significant
digits, so there was nothing to round. Replaced by the property that does hold,
and by one stating the rounding outright so the next reader does not repeat the
mistake I nearly shipped.

Also written down: why the setter rounds while the codec refuses more than
sixteen digits. They see different inputs. Seventeen digits cannot arrive from
the network - rippled normalises the mantissa into [1e15, 1e16) before
serialising - so the codec only ever meets a hand-written string, while the
setter meets computed decimals that routinely carry 28. AmmMath returns them.

…ed it

Release preparation for 27/08, found by checking what actually changed since
11.0.0.0 rather than by looking at this branch alone.

Xrpl.BinaryCodec/XrplBinaryCodec.cs changed in #147 and the package version did
not. Promoting that way publishes nothing: dotnet nuget push runs with
--skip-duplicate, so a package whose version already exists on the feed is
passed over in silence, and the fix reaches no consumer while the run stays
green. Moved to 11.0.1.0 - a performance fix with no contract change, so patch.

The same PR left no CHANGES.md entry. A 1.73x change on the path every signing
operation takes is not a silent one, so it has one now, with the measurement and
with why the usual telling of that bug oversells it.

Xrpl stays at 11.1.0.0: this release carries a contract change, since code that
read an out-of-range amount used to get a number and now gets an exception.
AddressCodec, Keypairs and both X402 packages are untouched and keep their
versions - they are consumed by ProjectReference, so a package built at a newer
version keeps depending on the published ones.

CHANGES.md still opens with "## Unreleased". Stamping it belongs to the
promotion, when the date is known.